Nornir Integration

Nornir is an automation framework written in Python for use in the development of applications that manage network devices. Nornir has its own inventory system for dealing with host information. It also handles the dispatching of tasks to your devices and provides a common framework to write “plugins”. Please visit the Nornir documentation page for more information.

Automation Gateway (AG) contains a Nornir Module Execution Engine that supports the discovery, decoration, and execution of Nornir modules. AG also provides support for managing Nornir device inventory files and plugins.

Note: Nornir version 3.0.0 is the minimum version supported by Automation Gateway.

A complete set of REST APIs are available for clients to manage Nornir inventory, module decoration, and execution. See the API Documentation section within the Automation Gateway UI for more information.

Inventory

Nornir inventory is composed of a host_file, group_file, and defaults_file. Different plugins are available to support various file formats. More details about inventory can be found in the Nornir documentation. A configuration file is used to indicate the location of the inventory files as well as the plugin type being utilized.

# cat config.yml
---
logging:
    enabled: False

inventory:
    plugin: SimpleInventory
    options:
        host_file: "/app/devtools/nornir/inventory/hosts.yaml"
        group_file: "/app/devtools/nornir/inventory/groups.yaml"
        defaults_file: "/app/devtools/nornir/inventory/defaults.yaml"
runner:
    plugin: threaded
    options:
        num_workers: 100
#

The path to the Nornir configuration file is provided to AG by setting the nornir_config_file parameter in properties.yml. Automation Gateway automatically consumes the Nornir inventory files found in the configuration file at startup. Users can access the inventory data via the /devices and /groups APIs.

#
# Name of Nornir configuration file.
# Uncomment this property if you will be using Nornir inventory.
#
nornir_config_file: /path/to/config.yaml

Discovery

The AG server performs discovery of Nornir modules at startup time and maintains a cache of all managed modules in memory. Users determine the modules being managed by providing a single path or a list of directory paths in their AG properties.yml configuration file. A recursive search of the directory paths is performed.

#
# Path(s) to the set of nornir modules you would like to invoke from Automation Gateway.
#
nornir_module_path: /usr/share/nornir/modules

Decoration

Once a module has been discovered, it is available to be decorated. The decoration of Nornir modules within Automation Gateway is similar to that of Ansible playbooks. However, instead of decorating the variables within a playbook, users decorate the command line arguments and environment variables used to execute a Nornir module. The decorated parameters are then passed as arguments to the APIs that execute the module. A permanent copy of each module's decoration is stored in a local database that is maintained by Automation Gateway.

The same features and functionality provided by AG for decorating proprietary scripts are available for decorating Nornir modules. See the Script Execution Engine section of the AG User Guide for complete instructions on module decoration.

Execution

Nornir modules are executed by issuing a POST {hostname:port}/nornir/{module_name}/execute call to Automation Gateway. Executing a module can be done using the Automation Gateway UI or by a separate application. Modules are executed on the node on which the AG server is running.

The desired arguments and environment variables that match the Nornir module's schema are included as execution parameters. The execution parameters are passed to the module as if they were being entered by the user on the command line. Part of the module's execution logic is to parse the contents of the command line accordingly.

By default, modules are executed from the home directory of the user that owns the Automation Gateway server process. To change the default execution directory, add the working_dir key to the module's schema outside the properties object. The value of working_dir can be an absolute or a relative directory path.

Hosts and Groups Support

The Nornir module execution API contains support for the hosts and groups parameters. The hosts parameter is an array of Nornir device names that are members of the AG inventory. Similarly, the groups parameter is an array of Nornir group names that are present in the AG inventory.

Note: The hosts and groups parameters are not required when executing a Nornir module.

When the hosts or groups parameters are present and their contents are validated, the Nornir Module Execution Engine will pass the contents to the Nornir module as a comma-separated list using the command line arguments --hosts and --groups. The Nornir module itself is responsible for parsing the contents of the --hosts and --groups arguments.

Results

The following fields are contained within the results object returned after execution of the module.